Combining Caps, Joins, Dashes, and Patterns (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /: Chapter 3 - Geometric Styles / Using Geometric Styles

Combining Caps, Joins, Dashes, and Patterns
As mentioned in "Interactions Between Caps, Joins, Dashes, and Patterns" on page 3-22, combining caps, joins, dashes, and patterns on the same shape causes some interesting interactions.
These elements interact differently in each of these three cases:

the shape does not have a dash but has one or more of the three other stylistic variations
the shape does have a dash but the clip dash attribute is not set
the shape does have a dash and the clip dash attribute is set

When a shape has a cap and a join, QuickDraw GX adds the caps to the beginnings and ends of the shape's contours, and adds the joins to the other on-curve geometric points of the shape's contours. If the shape also has a pattern, QuickDraw GX draws this pattern throughout the shape's frame as well as the shape's caps and joins. The sample function in Listing 3-21 creates an angle shape with a round cap, a square join, and a very small square pattern.
Listing 3-21 Combining a cap, join, and pattern
void CapJoinPattern(void)
{
   gxShape  anAngleShape, aRoundCap, aSquareJoin, aSquarePattern;

   static long angleGeometry[] = {1, /* number of contours */
                                  3, /* number of points */
                                  ff(100), ff(100),
                                  ff(200), ff(80), 
                                  ff(300), ff(100)};
      
   static long diamondGeometry[] = {1, /* number of contours */
                                    4, /* number of points */
                                    ff(0), ff(50), 
                                    ff(10), ff(0),
                                    ff(0), -ff(50), 
                                    -ff(10), ff(0)};
   
   static gxRectangle circleBounds ={-fl(.75), -fl(.75), 
                                     fl(.75), fl(.75)};
   static gxRectangle smallSquareGeometry = {ff(0), ff(0), 
                                             ff(1), ff(1)};
   gxCapRecord theCapRecord;
   gxJoinRecord theJoinRecord;
   gxPatternRecord thePatternRecord;
   
   /* Create the shape to be capped, joined, and patterned. */
   anAngleShape = GXNewPolygons((gxPolygons *) angleGeometry);
   GXSetShapeFill(anAngleShape, gxOpenFrameFill);
   GXSetShapePen(anAngleShape, ff(50));
   
   /* Create the round cap and add to the shape. */
   aRoundCap = NewArc(&circleBounds, ff(0), ff(360), false);
   theCapRecord.startCap = aRoundCap;
   theCapRecord.endCap = aRoundCap;
   theCapRecord.attributes = gxNoAttributes;
   GXSetShapeCap(anAngleShape, &theCapRecord);
   GXDisposeShape(aRoundCap);

   /* Create the square join and add to join the shape. */
   aSquareJoin = GXNewRectangle(&circleBounds);
   theJoinRecord.attributes = gxNoAttributes;
   theJoinRecord.join = aSquareJoin;
   theJoinRecord.miter = 0; 
   GXSetShapeJoin(anAngleShape, &theJoinRecord);
   GXDisposeShape(aSquareJoin);

   /* Create the small square pattern and pattern the shape. */
   aSquarePattern = GXNewRectangle(&smallSquareGeometry);
   GXSetShapeFill(aSquarePattern, gxSolidFill);
   thePatternRecord.attributes = gxNoAttributes;
   thePatternRecord.pattern = aSquarePattern;
   thePatternRecord.u.x = ff(0);
   thePatternRecord.u.y = ff(2);
   thePatternRecord.v.x = ff(2);
   thePatternRecord.v.y = ff(0);
   GXSetShapePattern(anAngleShape, &thePatternRecord);
   GXDisposeShape(aSquarePattern);
   
   GXDrawShape(anAngleShape);
   
   GXDisposeShape(anAngleShape);
}
The result of this function is shown in Figure 3-78.
Figure 3-78 Angle shape with cap, join, and pattern

The second case of cap, join, dash, and pattern interaction is when the shape has a dash but the clip dash attribute is not set. In this case, QuickDraw GX ignores the caps and joins of the shape. However, QuickDraw GX does draw the pattern throughout the dashes.
For example, if you add the following declarations at the appropriate places in the previous example:
gxShape aDiamondDash;
static long diamondGeometry[] = {1, /* number of contours */
                                 4, /* number of points */
                                 ff(0), ff(50), 
                                 ff(10), ff(0),
                                 ff(0), -ff(50), 
                                 -ff(10), ff(0)}; 
gxDashRecord theDashRecord;
and you add the following code to create a diamond-shaped dash:
/* Create the diamond dash and dash the shape. */
aDiamondDash = GXNewPolygons((gxPolygons *) diamondGeometry);
GXSetShapeFill(aDiamondDash, gxEvenOddFill);
theDashRecord.attributes = gxNoAttributes;  
theDashRecord.dash = aDiamondDash;
theDashRecord.advance = ff(40); 
theDashRecord.phase = 0; 
theDashRecord.scale = ff(50); 
GXSetShapeDash(anAngleShape, &theDashRecord);
GXDisposeShape(aDiamondDash);
the resulting shape will appear as depicted in Figure 3-79.
Figure 3-79 Angle shape with dash and pattern; caps and join ignored

The third case of cap, join, dash, and pattern interaction is when the shape has a dash and the clip dash attribute is set. In this case, QuickDraw GX adds the cap and the join shapes to the clip shape used to clip the dashes. Patterns are not allowed in this case, so if you add the following line to the previous example:
theDashRecord.attributes = gxClipDash;  
you must comment out this line:
/* GXSetShapePattern(anAngleShape, &thePatternRecord); */
which ensures that no pattern is set for the shape.
In this case, the resulting shape is drawn as shown in Figure 3-80.
Figure 3-80 Shape with cap, join, dash, and the clip dash attribute set

Notice that the dashes (which are now solid because there is no pattern) are clipped to the thick contours of the angle shape. However, at the ends and at the corner more of the dashes show because the cap shapes and the join shape are added to the clip shape used to clip the dashes.